package nl.windgazer.arachne.annotations;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import nl.windgazer.arachne.services.facebook.FacebookLikeMediumType;
import nl.windgazer.arachne.services.facebook.FacebookShareMediumType;

/**
 * I hope to use this annotation to supply a page with the standard FaceBook required information.
 * This Annotation will canibalise of of the IncludeOpenGraphMetaInfo annotation, or at least its'
 * *Worker class.<br />
 * 
 * For the 'image' it is assumed that it's either a full url starting with http, or a context/classpath
 * property to be evaluated as an asset using T5 classes.
 * 
 * <p><em>*** For now only literal values or values with a message: prefix can be used,
 * no other binding-prefixes are supported as yet.</em></p>
 * 
 * <p>The Open Graph protocol defines five required properties:</p>
 * <ul>
 * <li>og:title - The title of your object as it should appear within the graph, e.g., "The Rock".</li>
 * <li>og:type - The type of your object, e.g., "movie". See the complete list of supported types.</li>
 * <li>og:image - An image URL which should represent your object within the graph. The image must be at least 50px by 50px and have a maximum aspect ratio of 3:1.</li>
 * <li>og:url - The canonical URL of your object that will be used as its permanent ID in the graph, e.g., http://www.imdb.com/title/tt0117500/.</li>
 * <li>og:site_name - A human-readable name for your site, e.g., "IMDb"</li>
 * </ul>
 * <p>In addition, we've extended the basic meta data to add one required field to connect your page with :</p>
 * <ul>
 * <li>fb:admins or fb:app_id - A comma-separated list of either Facebook user IDs or a Facebook Platform application ID that administers this page.</li>
 * </ul>
 * <p>It's also recommended that you include the following property as well as these multi-part properties.</p>
 * <ul>
 * <li>og:description - A one to two sentence description of your page.</li>
 * </ul>
 * <p>This solution is based on information available from http://developers.facebook.com/docs/opengraph</p>
 * 
 * @see org.apache.tapestry5.annotations.Path
 * @see org.apache.tapestry5.annotations.IncludeJavaScriptLibrary
 * @author mreuring
 */
@Target({ ElementType.TYPE })
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface IncludeFaceBookOpenGraphInfo {

	/**
	 * The og:title meta-info is required to be able to use the 'like' link
	 * @return
	 */
	String title();

	/**
	 * The og:type meta-info is required to be able to use the 'like' link<br />
	 * Use article for any URL that represents transient content - such as a news 
	 * article, blog post, photo, video, etc. Do not use website for this purpose. 
	 * website and blog are designed to represent an entire site, an og:type tag 
	 * with types website or blog should usually only appear on the root of a domain.
	 * @return
	 */
	FacebookLikeMediumType type();
	
	/**
	 * The og:image meta-info is required to be able to use the 'like' link.<br />
	 * An image URL which should represent your object within the graph. The image 
	 * must be at least 50px by 50px and have a maximum aspect ratio of 3:1.
	 * @return
	 */
	String image() default "";

	/**
	 * The og:url meta-info is required to be able to use the 'like' link
	 * @return
	 */
	String url();

	/**
	 * The og:site_name meta-info is required to be able to use the 'like' link
	 * @return
	 */
	String site_name();

	/**
	 * The og:admins meta-info is optional to be able to use the 'like' link
	 * @return
	 */
	String admins() default "";

	/**
	 * The og:app_id meta-info is optional to be able to use the 'like' link
	 * @return
	 */
	String app_id() default "";

	/**
	 * The og:description meta-info is optional to be able to use the 'like' link
	 * @return
	 */
	String description() default "";

	/**
	 * The 'share' button uses a different 'type' which has been made optional. For certain
	 * types of 'media' additional meta-data may be required, or optional, see 
	 * http://wiki.developers.facebook.com/index.php/Facebook_Share/Specifying_Meta_Tags
	 * for a full description.
	 * ArachneRenderSupport can be injected and used to provide such extra meta-tags.
	 */
	FacebookShareMediumType medium() default FacebookShareMediumType.none;

}
